LGF_FileReadWriteDelete (FB / 1.0.0)

Author: Simatic Systems Support

Short description

The function LGF_FileReadWriteDelete can be used to read, write or delete a file to/from the SIMATIC Memory Card (SMC).

To read or write the data, it is necessary to deserialize/serialize it, which the function already does for the user. For this purpose, an external buffer in the form of a byte array must be connected, which can hold the amount of data; if the buffer is too small, an error is output.

The file name must always be specified in full together with the folder name and the file extension in the following format: UserFiles/Test.dat.

Block Interface


Bool	executeRead	done	Bool
Bool	executeRead	done	Bool
Bool	executeWrite	busy	Bool
Bool	executeWrite	busy	Bool
Bool	executeDelete	error	Bool
Bool	executeDelete	error	Bool
String	fileName	status	Word
String	fileName	status	Word
LGF_typeFileReadWriteDeleteParameter	parameter	dataLength	DInt
LGF_typeFileReadWriteDeleteParameter	parameter	dataLength	DInt
		fileDoesNotExist	Bool
		fileDoesNotExist	Bool
		timestamps	LGF_typeFileReadWriteDeleteTimestamps
		timestamps	LGF_typeFileReadWriteDeleteTimestamps
		diagnostics	LGF_typeDiagnostics
		diagnostics	LGF_typeDiagnostics
Array[*] of Byte	bufferByteArray		Array[*] of Byte
Array[*] of Byte			Array[*] of Byte
Variant	data		Variant
Variant			Variant

Input parameter

Identifier	Data type	Default value	Description
executeRead	Bool	FALSE	Rising edge starts file read once
executeWrite	Bool	FALSE	Rising edge starts file write once
executeDelete	Bool	FALSE	Rising edge starts file delete once
fileName	String	''	Name of file including path: `UserFiles/test.dat`
parameter	LGF_typeFileReadWriteDeleteParameter	---	This UDT belongs to the Module `LGF_FileReadWriteDelete` and lists all possible parameters to configure its behavior.

Output parameter

Identifier	Data type	Description
done	Bool	TRUE: Commanded functionality has been completed successfully
busy	Bool	TRUE: FB is not finished; new output values can be expected
error	Bool	TRUE: An error occurred during the execution of the functionality
status	Word	16#0000 - 16#7FFF: Status of the FB, 16#8000 - 16#FFFF: Error identification
dataLength	DInt	Data length read from file (serialized length of `data`)
fileDoesNotExist	Bool	True: The file or the path present at `fileName` does not exist
timestamps	LGF_typeFileReadWriteDeleteTimestamps	Timestamps for commands and file
diagnostics	LGF_typeDiagnostics	Diagnostic structure to store and transfer diagnostic information from blocks through the interface.

In/Out parameter

Identifier	Data type	Description
bufferByteArray	Array[*] of Byte	Byte array buffer for read / write from / to file
data	Variant	Data set read from file / to write to file

Status & Error codes

Code / Value	Identifier / Description
16#0000	STATUS_EXECUTION_FINISHED Execution finished without errors
16#7000	STATUS_NO_CALL No job being currently processed
16#7001	STATUS_FIRST_CALL First call after incoming new job (rising edge 'execute')
16#7002	STATUS_SUBSEQUENT_CALL Subsequent call during active processing without further details
16#8201	ERR_BUFFER_LOWERBOUND Error: Buffer array lower bound Lower bound must be 0
16#8202	ERR_BUFFER_ARRAY_TO_SMALL_TO_COPY Error: Buffer size less than needed size for data
16#8400	ERR_MULTIPLE_COMMANDS Error: Multiple commands add the same time not allowed.
16#8401	ERR_FILE_PATH Error: File path error: File path must start with 'UserFiles/'.
16#8402	ERR_READ_TIME_LOCAL Error: Read local time `RD_LOC_T`- see `diagnostics.subFunctionStatus`
16#8403	ERR_READ_TIME_SYSTEM Error: Read system time (UTC) `RD_SYS_T` - see `diagnostics.subFunctionStatus`
16#8411	ERR_FILE_SIZE_GRATER_THEN_DATA_SIZE Error: File length and Data length dose not match!
16#8412	ERR_FILE_SIZE_LESS_THEN_DATA_SIZE Error: File length and Data length dose not match!
16#8600	ERR_UNDEFINED_STATE Error due to an undefined state in state machine
16#8601	ERR_MOVE_BLK_VARIANT Error: Move block variant (buffer to data) - see `diagnostics.subFunctionStatus`
16#8602	ERR_SERIALIZE_DATA Error: Serialize data - see `diagnostics.subFunctionStatus`
16#8603	ERR_DESERIALIZE_DATA Error: Deserialize data - see `diagnostics.subFunctionStatus`
16#8604	ERR_SERIALIZE_DATE_TIMESTAMP Error: Serialize date and time stamp - see `diagnostics.subFunctionStatus`
16#8605	ERR_DESERIALIZE_DATE_TIMESTAMP Error: Deserialize date and time stamp - see `diagnostics.subFunctionStatus`
16#8610	ERR_FILE_READ_INIT Error: Read file Initialization from SMC - see `diagnostics.subFunctionStatus`
16#8611	ERR_FILE_READ Error: Read file from SMC - see `diagnostics.subFunctionStatus`
16#8620	ERR_FILE_WRITE_INIT Error: Write file Initialization to SMC - see `diagnostics.subFunctionStatus`
16#8621	ERR_FILE_WRITE Error: Write file to SMC - see `diagnostics.subFunctionStatus`
16#8630	ERR_FILE_DELETE_INIT Error: Delete file Initialization from SMC - see `diagnostics.subFunctionStatus`
16#8631	ERR_FILE_DELETE Error: Delete file from SMC - see `diagnostics.subFunctionStatus`

User defined datatype(s)

LGF_typeFileReadWriteDeleteParameter (UDT / V0.0.1)

This UDT belongs to the Module LGF_FileReadWriteDelete and lists all possible parameters to configure its behavior.

Identifier	Data type	Default value	Description
dataLengthMustMatch	Bool	TRUE	TRUE: The length of the file data set and the dataset in the PLC must match (File read)
clearBufferBefore	Bool	TRUE	TRUE: Buffer would be cleared with 16#00 Byte before writing the data (File write)
includeTimestamp	Bool	FALSE	TRUE: A Timestamp (DTL) is included in front of the Data. `executeWrite` adds the actual time (system- or local time) `executeRead` reads back the timestamp
timeStampIsLocal	Bool	FALSE	TRUE: The timestamp is used in local time. FALSE: The timestamp is used in system time / UTC. Only used if `includeTimestamp` is set.

LGF_typeFileReadWriteDeleteTimestamps (UDT / V0.0.1)

This UDT belongs to the module LGF_FileReadWriteDelete and lists all timestamps of the commands and the file, if known.
If the timestamp is unknown, the default timestamp is displayed: DTL#1970-01-01-00:00:00.

Identifier	Data type	Default value	Description
file	LGF_typeFileReadWriteDeleteTimestamp	---	Time stamp of file
lastCommand	LGF_typeFileReadWriteDeleteTimestamp	---	Time stamp of last command
executeRead	LGF_typeFileReadWriteDeleteTimestamp	---	Time stamp of command `executeRead`
executeWrite	LGF_typeFileReadWriteDeleteTimestamp	---	Time stamp of command `executeWrite`
executeDelete	LGF_typeFileReadWriteDeleteTimestamp	---	Time stamp of command `executeDelete`
lastError	LGF_typeFileReadWriteDeleteTimestamp	---	Time stamp of the last error that occurred

LGF_typeFileReadWriteDeleteTimestamp (UDT / V0.0.1)

This UDT belongs to the module LGF_FileReadWriteDelete and keeps a timestamp of a command or a file.
If the timestamp is unknown, the default timestamp is displayed: DTL#1970-01-01-00:00:00.

Identifier	Data type	Default value	Description
dateAndTime	DTL	---	Time stamp
timestampIsLocal	Bool	FALSE	TRUE: The timestamp is used in local time. FALSE: The timestamp is used in system time / UTC. Only used if `includeTimestamp` is set.

LGF_typeDiagnostics (UDT / V1.0.1)

Diagnostic structure to store and transfer diagnostic information from blocks through the interface.

Identifier	Data type	Default value	Description
status	Word	16#0000	Status of the Block or error identification when error occurred
subfunctionStatus	Word	16#0000	Status or return value of called FB's, FC's and system blocks
stateNumber	DInt	0	State in the state machine of the block where the error occurred

Functional description

All commands

The file name must always be specified in full together with the folder name and the file extension in the following format: UserFiles/test.dat.

Time stamps

Time stamps are written for commands, an error and the file, they are stored in the variable timestamps. In the event of an error, the timestamps of the individual commands are not written, the timestamp of the file is reset to the default value DTL#1970-01-01-00:00:00.

File Read - Command `executeRead`

With the command executeRead a file can be read into the data budget of a variable at data. To read the data it is necessary to deserialize it, which the function already takes from the user.
For deserialization an external buffer in the form of a byte array must be connected which can take up the amount of data, if the buffer is too small an error is output.

File Delete - Command `executeDelete`

With the command executeDelete a file can be deleted from the SIMATIC Memory Card (SMC). The file name must always be specified in full together with the folder name and the file extension in the following format: UserFiles/test.dat.

File Write - Command `executeWrite`

With the command executeWrite the data budget of a variable can be written to data in a file. For writing the data it is necessary to serialize it, which the function already takes from the user.
For serialization an external buffer in the form of a byte array must be connected which can take up the data quantity, if the buffer is too small an error is output.

Note: The file extension (here e.g. dat) can be freely selected or omitted, it is useful for external processing to indicate the format of the file to the user.; A file extension in the file name has no influence on the content of the file as well as its formatting, providing the data in an appropriate file format is up to the user.

Warning: The SMC (SIMATIC Memory Card) is a flash memory with finite writing cycles.; A high frequent write access therefore also affects the lifetime of the SMC!

Change log

Version & Date		Change description
	1.0.0	Simatic Systems Support
	10.07.2025	First released version